表記揺れを治すために表記統一リストを作成して、textlint で検知・修正する
2024.10.25社内のエンジニアチームにてナレッジサイト(Classmethod Cloud Guidebook[1])を運営しています。
ナレッジサイト(Classmethod Cloud Guidebook)
おおよそ2年ほど継続して追記・更新しており、 ドキュメント量も増えてきました。 また、複数人(=社内のエンジニア)が関わる環境なので、 人によって書きっぷりも異なってきます。
$ cat docs/**/*.md | wc -lm
13061 446458
# ↑ ナレッジサイトの総ページは 1万行以上、40万文字以上
社内リポジトリのコントリビューター数は41人(2024/10/25時点)
もともと textlint 自体による自動校正は導入していました(参考)。 技術文書向けのルールセット(preset-ja-technical-writing)を活用して、 ある程度の品質は担保されていました。
しかし、細かい表記揺れは校正できていませんでした。 たとえば すべき/するべき といった語尾の表現や サーバ/サーバー などのカタカナ表記などです。 その他にも CMメンバーズ/クラスメソッドメンバーズ といった専門用語の表記揺れもありました。
そういった背景があり、よりドキュメントの品質を上げるべく 表記統一リスト を作成しました。 それをベースに、 textlint の各種ルールを 活用して表記揺れを検知・修正する仕組みを作ってみます。
計画の概要
実施した内容は以下のとおりです。それぞれ順番に説明していきます。
- 表記揺れのカテゴリ を決める
- 表記揺れを洗い出して 表記統一リスト を作成する
- 表記統一リストを基に textlint による検知・修正の仕組み を作る
1. 表記揺れのカテゴリを決める
表記統一リストを今後メンテナンスしやすくするために、 表記揺れを以下8つにカテゴリ分けしました。
- 語尾や接続表現
- 漢字とひらがな
- カタカナ表記
- 送り仮名
- 数字や全角/半角
- 英字・カタカナ
- 略語
- 専門用語
語尾や接続表現
代表的なものは「ですます調/である調」の表記揺れです。 ほかにも「すべき/するべき」や 「することができます/できます」といった言い回しの表記揺れが対象です。
これらは文章の印象に与える影響が大きいため、統一する価値がある部分です。
漢字とひらがな
「おこなう/行う」や「ください/下さい」などは 表記揺れが特に発生しやすいです。
読みやすさに重きをおいて統一ルールを作成していきます。
カタカナ表記
外来語のカタカナ表記も表記揺れが多いです。 「サーバー/サーバ」や「ユーザー/ユーザ」などです。
送り仮名
「取り扱い/取扱い」、「割り当て/割当て」といった 送り仮名を省略されうるものは統一ルールを作成する価値があります。
数字や全角/半角
数字の表現も「ひとつ/1つ/１つ/一つ」というように さまざまな表記があります。
また、括弧の表現も「 全角の括弧 （） 」 と「 半角の括弧 () 」 で、 どちらを使うか分かれるところです。
英字・カタカナ
英字で書くか、カタカナで書くかの表記揺れになります。 たとえば「DBインスタンス/データベースインスタンス」、 「web ACL/ウェブACL」などです。
略語
「マネジメントコンソール/マネコン」や「オンプレミス/オンプレ」 などの良く使われる略語について、統一ルールを作成します。
専門用語
AWSサービスの正式名称や 自社のサービスの名称は 統一する価値がある部分です。
AWSサービスを正式名称で記載することはもちろん、 自社サービスの表記(「クラスメソッドメンバーズ/CMメンバーズ」など) を統一するためのルールを定めます。
2. 表記統一リストを作成する
先ほど決めたカテゴリごとに 表記揺れをどんどん洗い出していきます。 「望ましくない表記 → 望ましい表記」のテーブルを作成していきます。
表記統一リスト
洗い出しにあたって実施したことを紹介していきます。
- 執筆メンバーで洗い出し
- textlint 同義語チェックの活用
- 生成AIの活用
執筆メンバーで洗い出し
社内のメンバー間でドキュメントを読み合わせながら、 表記揺れを洗い出していきます。 素朴な方法ですが重要です。
厳しすぎるルールは、逆に執筆の足かせになりえます。 普段よく執筆しているメンバーの意見を集めながら、表記統一リストを作成していきます。
textlint 同義語チェックの活用
textlint の textlint-rule-no-synonyms は、 文章中の同義語表記揺れをチェックできる便利なルールです。 同義語の辞書として Sudachi 同義語辞書 が使われています。
既存のドキュメントにこのチェックを走らせて、同義語を洗い出します。
# ドキュメントを1ファイルにまとめる
cat ./docs/**/*.md > ./tmp_all.md
# textlint-rule-no-synonyms ルールでチェック(導入部分は割愛)
npx textlint --rule @textlint-ja/no-synonyms ./tmp_all.md
以下出力サンプルです。
~/ccg/docs/tmp_all.md
525:33 error 同義語である「および」と「及び」が利用されています @textlint-ja/no-synonyms
1709:23 error 同義語である「割り当て」と「割当」が利用されています @textlint-ja/no-synonyms
1714:38 error 同義語である「サーバー」と「サーバ」が利用されています @textlint-ja/no-synonyms
3518:29 error 同義語である「パラメータ」と「パラメーター」が利用されています @textlint-ja/no-synonyms
4067:29 error 同義語である「漏洩」と「漏えい」が利用されています @textlint-ja/no-synonyms
5023:34 error 同義語である「クラスター」と「クラスタ」が利用されています @textlint-ja/no-synonyms
5032:51 error 同義語である「繋がり」と「つながり」が利用されています @textlint-ja/no-synonyms
...(略)
生成AIの活用
さらに生成AIも活用して表記揺れを洗い出しました。 ツールとしては、自社の 生成AI環境構築サービスである「 AI-Starter 」を活用しました。
以下のようなプロンプトを何度も走らせて、表記揺れを見つけます。 アシスタントとしては Claude 3.5 Sonnet v2 を使いました。
あなたは文章校正のエキスパートです。
添付したドキュメントを注意深く読んでください。
ドキュメントのクオリティに影響するような表記揺れを見つけてリスト化してください。
リストは以下に示す適切なカテゴリに分けて出力してください。
- 語尾や接続表現
- 漢字とひらがな
- カタカナ表記
- 送り仮名
- 数字や全角/半角
- ローマ字・カタカナ
- 略語
- 専門用語
以下のようにいい感じに洗い出してくれます。
ただしドキュメント内にはそもそも無い表記揺れがあったり、 許容されるような表記揺れ(+ そもそも表記揺れではなさそうなもの)も多くありました。
そのため、最終的には人の判断で表記統一リストに反映させます。
3. textlintによる検知・修正の仕組みを作る
表記統一リストをベースに textlint ルールを実装していきます。 主に以下ルールを活用していく予定です。
- AWS関連の用語 → bun913/textlint-rule-aws-service-name
- ですます調/である調の統一 → textlint-ja/textlint-rule-no-mix-dearu-desumasuxtlint
- そのほか表記揺れ全般 → textlint-rule/textlint-rule-prh
それぞれ説明していきます。
AWS用語は aws-service-name ルールを活用
上記ブログで紹介されている aws-service-name ルールを使って、 AWSサービス名の表記揺れを検出できます。 AWSに関するドキュメントを扱っているのでとても重宝しています。
ですます調の統一は no-mix-dearu-desumasu ルールを活用
ですます調は no-mix-dearu-desumasu ルールを適用するのが便利です。
そのほかは prh ルールを活用
そのほかの表記揺れは textlint-rule-prh を使って対応できないか検討します。 このルールは校正を手伝ってくれるライブラリである proofreading-helper(prh) を textlint プラグインとしたものです。
以下のように表記統一リストの内容を prh.yml として記載します。
version: 1
rules:
### 語尾や接続表現
- expected: すべき
pattern:
- するべき
### 漢字とひらがな
- expected: おこなう
pattern:
- 行う
- 行なう
- expected: すべて
pattern:
- 全て
- expected: および
pattern:
- 及び
### カタカナ表記・外来語
- expected: ユーザー
pattern: /ユーザ(?!ー)/
- expected: サーバー
pattern: /サーバ(?!ー)/
- expected: レイヤー
pattern: /レイヤ(?!ー)/
### 送り仮名
- expected: 取り扱い
pattern: 取扱い
- expected: 割り当て
pattern: 割当て
### 数字や全角・半角
- expected: ひとつ
pattern:
- 一つ
- 1つ
### 英字・カタカナ
- expected: "web ACL"
pattern:
- "ウェブACL"
- "ウェブ ACL"
### 略語
- expected: オンプレミス
pattern: /オンプレ(?!ミス)/
specs:
- from: オンプレ
to: オンプレミス
- from: オンプレミス
to: オンプレミス
### 専門用語
- expected: "クラスメソッドメンバーズ"
pattern:
- "CMメンバーズ"
prh.yml をベースに検知・修正できるように textlint 設定を更新します。
{
"rules": {
"prh": {
"rulePaths": [
"./prh.yml"
]
}
}
}
以下出力例です。
$ npx textlint ./docs/SecurityHubGuide/AFSBP.md
~/ccg/docs/SecurityHubGuide/AFSBP.md
# ...略
525:33 ✓ error 及び => および prh
# ...略
620:43 ✓ error 漏洩 => 漏えい prh
664:20 ✓ error 下さい => ください prh
# ...略
727:43 ✓ error サーバ => サーバー prh
728:8 ✓ error サーバ => サーバー prh
731:30 ✓ error 下さい => ください prh
733:19 ✓ error 下さい => ください prh
# ...略
887:33 ✓ error サーバ => サーバー prh
890:76 ✓ error するべき => すべき prh
おわりに
表記揺れ解消プロセスのサンプルでした。
表記揺れを解消するには表記統一リストを作成して チームメンバーに浸透させる必要があります。 また、自動化できる部分はどんどん自動化したいです。 自動化には textlint が役に立ちます。
以上、参考になれば幸いです。
参考
